<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<!--  -->
<html> <head>
<title>Implementing and Using Local Objects</title>
</head>

<body text="#000000" bgcolor="#FFFFFF">
<h1>Implementing Local Objects</h1>

<p>The new addition of "<code>local</code>" interfaces in CCM define a
standard behavior of locality constraint object.  There are some
subtle differences in implementing and using local interfaces compared
to regular (remote) interfaces.  This page tries to collect
information on things to notice and common pitfalls.</p>

<ul>
  <li><p><b>Local or not Local?</b> - A local interface is local.
      Any types defined withing the interface are also local.  They
      include "struct, union, enum, sequence, exceptions, typedef..."
      For constructed types, if a constructed type contains local
      elements, then it also becomes local even if the type is not
      defined within a local interface.</p>

  <li><p>You can not put objects of local types into Any's or try to use
      it regular CORBA invocations.</p>

  <li><p><b>Implementation class</b> - Instead of inheriting from
      <code>POA_FOOBAR</code> class, the implementation of local
      interface inherit from both the C++ object mapping class (the
      client side class) and the <code>CORBA::LocalObject</code>.  For
      example, when <code>FOOBAR</code> is a regular interface, the
      declaration of the implementation class is something like this:
<pre>

        class FOOBAR_i : public virtual POA_FOOBAR
        {
          .  .  .
        };

</pre>
      However, if <code>FOOBAR</code> is defined as a local interface,
      the implementation class is defined as:
<pre>

        class FOOBAR_i : public virtual FOOBAR,
                         public virtual CORBA::LocalObject
        {
          .  .  .
        };

</pre></p>

  <li><p><b>Reference Counting and Object Reference Lifecycle 
      (TAO 1.6.5 and above, which followed the IDL->C++ mapping version 1.2)</b> -
      TAO 1.6.5 and above has been updated to the 1.2 IDL to C++ mapping.
      LocalObject is now refcounted by default. Regular CORBA object
      references use reference counting to manage lifecycle of object
      references. Local object references also use reference counting
      for lifecycle management. In that respect, Local Objects behave
      exactly as Regular CORBA objects do, and the memory management
      rules that apply to Regular CORBA objects apply to Local Objects
      </p>

      <p>If, for some reason, you would like to preserve the originial 
      behavior (i.e., disabling reference counting) then override 
      <code>_add_ref ()</code> and <code>_remove_ref
      ()</code> and implement them as no-op operations.</p>


  <li><p><b>Reference Counting and Object Reference Lifecycle (Prior to 
            TAO 1.6.5, which followed the IDL->C++ mapping version 1.1)</b> -
      Regular CORBA object references use reference counting to manage
      lifecycle of object references.  Local object references
      <b>may</b> also use reference counting for lifecycle
      management.</p>

      <p>There are <code>_add_ref ()</code> and <code>_remove_ref
      ()</code> operations defined in all local object and the ORB
      uses these operations to increase/decrease the reference count
      when <code>_duplicate ()</code> or <code>CORBA::release
      ()</code> are invoked on an ojbect reference.  <b>However,
      notice that the default implementation of <code>_add_ref
      ()</code> and <code>_remove_ref ()</code> for local objects are
      no-ops.</b>  Therefore, if you wish to do reference counting on
      your local object instances, you must overwrite <code>_add_ref
      ()</code> and <code>_remove_ref ()</code> in your implementation
      for that local object.</p>

      <p>By leaving <code>_add_ref ()</code> and <code>_remove_ref
      ()</code> as no-ops, you assume the responsibility of managing
      the local object instance.  Objects that have the same lifetime
      as the ORB may want to use this strategy and let the ORB to
      manage these instances of local objects.  This prevents user
      errors from crashing the server process.  However, in this case,
      the object needs to be <code>delete</code>'d explicitly (as
      <code>CORBA::release ()</code> basically doesn't do anything in
      this case.</p>

      <p>TAO developers can get reference counting by using the mixin class 
      <code>TAO_Local_Ref_Counted_Object ()</code> as:

      <pre>
       class FOOBAR_i : public virtual FOOBAR,
                        public virtual TAO_Local_Ref_Counted_Object
       {
          .  .  .
       };
       </pre>

      if you wish to use reference counting.  However,
      this is not portable and should be used with care by the applications.</p>

</ul>


<hr>
<address></address>
<!-- hhmts start -->
Last modified: Tue Jun  3 15:19:18 UTC 2008
<!-- hhmts end -->
</body> </html>
